home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / ovrsub.com / OVRSUB.DOC < prev    next >
Encoding:
Text File  |  1990-01-05  |  10.8 KB  |  220 lines
  1.                                   OVRSUB
  2.                                 Version 1.0
  3.                                 Ron Schuster
  4.  
  5. Overview
  6. ----------------------------------------------------------------------------
  7.  
  8. Some Turbo Pascal programmers have expressed the need to be able to use the OVR
  9. file from one version of a program with the EXE file from a different version
  10. of the same program.  The following excerpt from a message from Ed Rayl
  11. [73210,3446] illustrates one such situation:
  12.  
  13. "I have written an insurance premium finance program for a client that supports
  14. a standard form used by their business.  I got a request to support additional
  15. forms as they show up.  My print forms procedure is a single procedure (with
  16. several nested procedures) called PrintTheForm with no parameters.  It grabs
  17. information from globals as necessary.  The main .EXE is going to be
  18. copy-protected by Vault Corp. (yuk!) and I have no choice in this matter.  The
  19. client would like to send one print procedure to each of their clients, based
  20. on the form they use.  It occured to me to use an overlay for this.  I would
  21. simply put PrintTheForm in a unit and overlay it.  As new forms show up, I
  22. would simply replace the .OVR file with a new one.  The original EXE file
  23. CANNOT be modified on disk.  Vault does its magic by encrypting the EXE and
  24. then using a 'loader' program to un-encrypt it.  Once it is in memory, you can
  25. do anything you want, however."
  26.  
  27. Normally this cannot be done since the EXE file contains detailed information
  28. about the OVR file, and this information would be incorrect if a different
  29. OVR file was substituted for the original.  OvrSub overcomes this
  30. restriction.  It also lets you write a program that uses several different
  31. overlay files, each containing a different version of the same routines, and
  32. switch between them dynamically.  The demo program provides an example of
  33. this technique.  The file MAKEDEMO.BAT contains instructions for creating
  34. and running the demo.
  35.  
  36.  
  37. How it works
  38. -----------------------------------------------------------------------------
  39.  
  40. Data about the overlaid units in a program, such as the location and size of
  41. each unit's code in the OVR file, is embedded in the EXE file in what are
  42. called the "static dispatchers."  For more information about this, download
  43. the file OVRLAY.TXT from CompuServe (BPROGA lib 2).  When you run the program
  44. OVRPREP, it extracts this data from the EXE file and appends it to the end of
  45. the OVR file.  (I will refer to this information as the "OVRPREP data" in the
  46. rest of this document.  The format of this data is documented in OVRPREP.PAS.)
  47. In the application program you must call the procedure OvrSubstitute right
  48. after your call to OvrInit.  This reads the OVRPREP data from the end of the
  49. OVR file and adjusts the static dispatchers in memory.  Note that the EXE file
  50. is never actually modified.  The result of these adjustments is that calls in
  51. the old EXE to procedures in overlaid units find their way to the right place
  52. in the code contained in the new OVR file.
  53.  
  54.  
  55. Creating the OVR files
  56. -----------------------------------------------------------------------------
  57.  
  58. The file MAKEDEMO.BAT is a brute force implementation of this approach.  I
  59. imagine a Make utility could be used to good advantage here.
  60.  
  61. 1.  Add a call to OvrSubstitute after your call to OvrInit.
  62. 2.  With the proper source code for this version in place, compile the program
  63.     to produce EXE, OVR and MAP files.
  64. 3.  Run OVRPREP.
  65. 4.  Rename the OVR file with an appropriate name for this version.
  66. 5.  Repeat steps 2 to 4 for each version of the OVR file.
  67.  
  68.  
  69. Compatibility
  70. -----------------------------------------------------------------------------
  71.  
  72. In order for multiple versions of your OVR file to work with a single EXE
  73. file, they must all be "compatible."  If they are not, a program crash is
  74. likely.  Error checks are built into OvrSubstitute to try to ensure
  75. compatibility before proceeding with a given OVR file.  Comparing reports from
  76. Kim Kokkonen's OVRSIZ from each OVR file version can also be useful here.
  77.  
  78. To achieve compatibility, the compilation of each version of your OVR file
  79. should produce the same, or nearly the same, EXE file.  Since each OVR file
  80. will ultimately be operating with one single EXE file, any references within
  81. the overlaid code to locations within the non-overlaid segments of the
  82. program must match.  All but the most trivial unit will have these references,
  83. since these include the Data segment and the System unit.
  84.  
  85. One thing that can cause trouble here is the smart linker.  It may alternately
  86. leave in and strip out non-overlaid code during the compilation of different
  87. versions of the OVR file depending on what procedures are referenced in each.
  88.  
  89. Another potential hazard is a difference in the "entry point count" from one
  90. OVR to another.  The entry point count is the total number of procedures and
  91. functions within an overlaid unit.  Ideally, each unit should have the same
  92. number of procedures and functions in the same order in each version of the
  93. OVR file.   However, you may have some flexibility if you want to add one or
  94. two functions or procedures in one OVR that don't exist in the other.  Each
  95. entry point adds 5 bytes to the size of the static dispatcher.  Since the
  96. size of the segment is always rounded up to the next paragraph, there's often
  97. room for an extra vector or two without causing any trouble, but cross that
  98. boundary and you throw off the address of every segment following the
  99. overlaid unit.  In any case, it's probably never a very good idea to change
  100. the interface section.
  101.  
  102.  
  103. OVRPREP
  104. -----------------------------------------------------------------------------
  105.  
  106. OVRPREP is supplied in source form, so you'll first need to compile it to an
  107. EXE file.  OVRPREP uses only the standard DOS unit.
  108.  
  109. To use OVRPREP, first compile the overlaid application to create the EXE and
  110. OVR files and a corresponding MAP file.  From within the TURBO integrated
  111. environment, you enable a MAP file with the Options/Linker/Map File/Segments
  112. menu.  For the command line compiler, use the /GS option.  OVRPREP reads only
  113. the first section of the MAP file (the segment map) to get certain
  114. information.  It doesn't hurt to have a detailed MAP file, but that takes more
  115. time and disk space to store.  OVRPREP also reads from your EXE file to get
  116. detailed information about the overlays.  This information is then appended
  117. to the OVR file.
  118.  
  119. Call OVRPREP as follows:
  120.  
  121.   OVRPREP [Options] ProgName [>Output]
  122.  
  123. OVRPREP forces the extensions 'EXE', 'MAP', and 'OVR' onto ProgName to find
  124. the corresponding files.  The only option at present is /Q, which stops OVRPREP
  125. from writing status messages while it works.
  126.  
  127.  
  128. The OVRSUB Unit
  129. -----------------------------------------------------------------------------
  130.  
  131. The OVRSUB unit interfaces the functions OvrSubstitute and OvrClose.  The
  132. OvrSubstitute function reads the OVRPREP data from the OVR file and uses it to
  133. adjust the static dispatchers in memory.  The OvrClose function clears all
  134. code from the overlay buffer and closes the current OVR file.  This is useful
  135. for dynamic overlay file switching.
  136.  
  137.  
  138. OvrSubstitute
  139. -----------------------------------------------------------------------------
  140.  
  141. Function        Reads the data appended to the OVR file by OVRPREP (the
  142.                 "OVRPREP data") and adjusts the static dispatchers in memory
  143.                 accordingly.
  144.  
  145. Declaration     function OvrSubstitute (CheckOverlayInfo, CheckEntryPts,
  146.                          CheckStaticSegs, CheckDataSeg : Boolean) : Word;
  147.  
  148. OvrSubstitute must be called immediately after your call to OvrInit.  The
  149. parameters enable or disable various error checks.  In general, the checks
  150. attempt to ensure that the current OVR file is compatible with the EXE
  151. file that is running.  If you disable any of these, you do so at your
  152. own risk.
  153.  
  154. CheckOverlayInfo determines the result code returned by OvrSubstitute if the
  155. OVRPREP data is not present in the OVR file.  If CheckOverlayInfo is true,
  156. OvrSubstitute will return an error code.  Otherwise OvrSubstitute will return
  157. a normal completion code.  Setting CheckOverlayInfo true protects against
  158. running the EXE file with an OVR file that has not been prepared with OVRPREP,
  159. which can cause a system crash if the EXE and OVR files are incompatible.
  160. However, this can be a nuisance during development since it requires you run
  161. OVRPREP after every compilation.
  162.  
  163. If CheckEntryPts is true, OvrSubstitute compares the entry point counts from
  164. each static dispatcher to the values recorded in the OVRPREP data and
  165. returns an error code if any mismatch is found.
  166.  
  167. If CheckStaticSegs is true, OvrSubstitute compares the segment address of the
  168. static dispatcher for each overlaid unit with the value recorded in the
  169. OVRPREP data and returns an error code if any mismatch is found.
  170.  
  171. If CheckDataSeg is true, OvrSubstitute compares the address of the current
  172. data segment with the value recorded in the OVRPREP data and returns an
  173. error code if a mismatch is found.
  174.  
  175.  
  176. The following return codes are defined for OvrSubstitute:
  177.  
  178. 0       Successful completion
  179. 1       Overlay manager not initialized.  OvrInit was not called.
  180. 2       At least one overlaid unit already loaded in overlay buffer.
  181. 3       Overlay file I/O error.  This may occur due to a difference in the
  182.         number of overlaid units in the EXE and OVR files.
  183. 4       OVRPREP data not found in OVR file and CheckOverlayInfo is true.
  184. 5       Static Segment Address mismatch found and CheckStaticSegs is true.
  185. 6       Entry Point Count mismatch found and CheckEntryPts is true.
  186. 7       Data Segment mismatch found and CheckDataSeg is true.
  187. 8       OvrSetBuf call failed.  Check the error code in OvrResult.
  188.  
  189.  
  190. OvrClose
  191. -----------------------------------------------------------------------------
  192.  
  193. Function        Clears all code from the overlay buffer and closes the
  194.                 current OVR file.
  195.  
  196. Declaration     function OvrClose : Word;
  197.  
  198. OvrClose is useful for dynamic overlay file switching.  After closing one OVR
  199. file, you can open another with a call to OvrInit using a different file name.
  200. Be sure each OvrInit call is followed by a call to OvrSubstitute.
  201.  
  202. The following return codes are defined for OvrClose:
  203.  
  204. 0       Successful completion
  205. 1       OvrDosHandle invalid or not open
  206.  
  207.  
  208. About the Programs
  209. -----------------------------------------------------------------------------
  210.  
  211. OVRSUB was written by Ron Schuster. It is copyright (c) 1989, all rights
  212. reserved.  It may be distributed freely, but not for a profit.
  213.  
  214. OVRPREP was derived from OVRSIZ, written by Kim Kokkonen of TurboPower
  215. Software. It is copyright (c) 1989 by TurboPower Software, all rights
  216. reserved. It may be distributed freely, but not for a profit.
  217.  
  218. If you have problems, suggestions, or enhancements, contact me on CompuServe
  219. ID [76666,2322].
  220.